home *** CD-ROM | disk | FTP | other *** search
/ IRIX Base Documentation 2002 November / SGI IRIX Base Documentation 2002 November.iso / usr / share / catman / p_man / cat3 / SCSL / sggesx.z / sggesx
Encoding:
Text File  |  2002-10-03  |  12.1 KB  |  331 lines
  1.  
  2.  
  3.  
  4. SSSSGGGGGGGGEEEESSSSXXXX((((3333SSSS))))                                                          SSSSGGGGGGGGEEEESSSSXXXX((((3333SSSS))))
  5.  
  6.  
  7.  
  8. NNNNAAAAMMMMEEEE
  9.      SGGESX - compute for a pair of N-by-N real nonsymmetric matrices (A,B),
  10.      the generalized eigenvalues, the real Schur form (S,T), and,
  11.  
  12. SSSSYYYYNNNNOOOOPPPPSSSSIIIISSSS
  13.      SUBROUTINE SGGESX( JOBVSL, JOBVSR, SORT, SELCTG, SENSE, N, A, LDA, B,
  14.                         LDB, SDIM, ALPHAR, ALPHAI, BETA, VSL, LDVSL, VSR,
  15.                         LDVSR, RCONDE, RCONDV, WORK, LWORK, IWORK, LIWORK,
  16.                         BWORK, INFO )
  17.  
  18.          CHARACTER      JOBVSL, JOBVSR, SENSE, SORT
  19.  
  20.          INTEGER        INFO, LDA, LDB, LDVSL, LDVSR, LIWORK, LWORK, N, SDIM
  21.  
  22.          LOGICAL        BWORK( * )
  23.  
  24.          INTEGER        IWORK( * )
  25.  
  26.          REAL           A( LDA, * ), ALPHAI( * ), ALPHAR( * ), B( LDB, * ),
  27.                         BETA( * ), RCONDE( 2 ), RCONDV( 2 ), VSL( LDVSL, * ),
  28.                         VSR( LDVSR, * ), WORK( * )
  29.  
  30.          LOGICAL        SELCTG
  31.  
  32.          EXTERNAL       SELCTG
  33.  
  34. IIIIMMMMPPPPLLLLEEEEMMMMEEEENNNNTTTTAAAATTTTIIIIOOOONNNN
  35.      These routines are part of the SCSL Scientific Library and can be loaded
  36.      using either the -lscs or the -lscs_mp option.  The -lscs_mp option
  37.      directs the linker to use the multi-processor version of the library.
  38.  
  39.      When linking to SCSL with -lscs or -lscs_mp, the default integer size is
  40.      4 bytes (32 bits). Another version of SCSL is available in which integers
  41.      are 8 bytes (64 bits).  This version allows the user access to larger
  42.      memory sizes and helps when porting legacy Cray codes.  It can be loaded
  43.      by using the -lscs_i8 option or the -lscs_i8_mp option. A program may use
  44.      only one of the two versions; 4-byte integer and 8-byte integer library
  45.      calls cannot be mixed.
  46.  
  47. PPPPUUUURRRRPPPPOOOOSSSSEEEE
  48.      SGGESX computes for a pair of N-by-N real nonsymmetric matrices (A,B),
  49.      the generalized eigenvalues, the real Schur form (S,T), and, optionally,
  50.      the left and/or right matrices of Schur vectors (VSL and VSR).  This
  51.      gives the generalized Schur factorization
  52.  
  53.           (A,B) = ( (VSL) S (VSR)**T, (VSL) T (VSR)**T )
  54.  
  55.      Optionally, it also orders the eigenvalues so that a selected cluster of
  56.      eigenvalues appears in the leading diagonal blocks of the upper quasi-
  57.      triangular matrix S and the upper triangular matrix T; computes a
  58.      reciprocal condition number for the average of the selected eigenvalues
  59.      (RCONDE); and computes a reciprocal condition number for the right and
  60.  
  61.  
  62.  
  63.                                                                         PPPPaaaaggggeeee 1111
  64.  
  65.  
  66.  
  67.  
  68.  
  69.  
  70. SSSSGGGGGGGGEEEESSSSXXXX((((3333SSSS))))                                                          SSSSGGGGGGGGEEEESSSSXXXX((((3333SSSS))))
  71.  
  72.  
  73.  
  74.      left deflating subspaces corresponding to the selected eigenvalues
  75.      (RCONDV). The leading columns of VSL and VSR then form an orthonormal
  76.      basis for the corresponding left and right eigenspaces (deflating
  77.      subspaces).
  78.  
  79.      A generalized eigenvalue for a pair of matrices (A,B) is a scalar w or a
  80.      ratio alpha/beta = w, such that  A - w*B is singular.  It is usually
  81.      represented as the pair (alpha,beta), as there is a reasonable
  82.      interpretation for beta=0 or for both being zero.
  83.  
  84.      A pair of matrices (S,T) is in generalized real Schur form if T is upper
  85.      triangular with non-negative diagonal and S is block upper triangular
  86.      with 1-by-1 and 2-by-2 blocks.  1-by-1 blocks correspond to real
  87.      generalized eigenvalues, while 2-by-2 blocks of S will be "standardized"
  88.      by making the corresponding elements of T have the form:
  89.              [  a  0  ]
  90.              [  0  b  ]
  91.  
  92.      and the pair of corresponding 2-by-2 blocks in S and T will have a
  93.      complex conjugate pair of generalized eigenvalues.
  94.  
  95.  
  96.  
  97. AAAARRRRGGGGUUUUMMMMEEEENNNNTTTTSSSS
  98.      JOBVSL  (input) CHARACTER*1
  99.              = 'N':  do not compute the left Schur vectors;
  100.              = 'V':  compute the left Schur vectors.
  101.  
  102.      JOBVSR  (input) CHARACTER*1
  103.              = 'N':  do not compute the right Schur vectors;
  104.              = 'V':  compute the right Schur vectors.
  105.  
  106.      SORT    (input) CHARACTER*1
  107.              Specifies whether or not to order the eigenvalues on the diagonal
  108.              of the generalized Schur form.  = 'N':  Eigenvalues are not
  109.              ordered;
  110.              = 'S':  Eigenvalues are ordered (see SELCTG).
  111.  
  112.      SELCTG  (input) LOGICAL FUNCTION of three REAL arguments
  113.              SELCTG must be declared EXTERNAL in the calling subroutine.  If
  114.              SORT = 'N', SELCTG is not referenced.  If SORT = 'S', SELCTG is
  115.              used to select eigenvalues to sort to the top left of the Schur
  116.              form.  An eigenvalue (ALPHAR(j)+ALPHAI(j))/BETA(j) is selected if
  117.              SELCTG(ALPHAR(j),ALPHAI(j),BETA(j)) is true; i.e. if either one
  118.              of a complex conjugate pair of eigenvalues is selected, then both
  119.              complex eigenvalues are selected.  Note that a selected complex
  120.              eigenvalue may no longer satisfy
  121.              SELCTG(ALPHAR(j),ALPHAI(j),BETA(j)) = .TRUE. after ordering,
  122.              since ordering may change the value of complex eigenvalues
  123.              (especially if the eigenvalue is ill-conditioned), in this case
  124.              INFO is set to N+3.
  125.  
  126.  
  127.  
  128.  
  129.                                                                         PPPPaaaaggggeeee 2222
  130.  
  131.  
  132.  
  133.  
  134.  
  135.  
  136. SSSSGGGGGGGGEEEESSSSXXXX((((3333SSSS))))                                                          SSSSGGGGGGGGEEEESSSSXXXX((((3333SSSS))))
  137.  
  138.  
  139.  
  140.      SENSE   (input) CHARACTER
  141.              Determines which reciprocal condition numbers are computed.  =
  142.              'N' : None are computed;
  143.              = 'E' : Computed for average of selected eigenvalues only;
  144.              = 'V' : Computed for selected deflating subspaces only;
  145.              = 'B' : Computed for both.  If SENSE = 'E', 'V', or 'B', SORT
  146.              must equal 'S'.
  147.  
  148.      N       (input) INTEGER
  149.              The order of the matrices A, B, VSL, and VSR.  N >= 0.
  150.  
  151.      A       (input/output) REAL array, dimension (LDA, N)
  152.              On entry, the first of the pair of matrices.  On exit, A has been
  153.              overwritten by its generalized Schur form S.
  154.  
  155.      LDA     (input) INTEGER
  156.              The leading dimension of A.  LDA >= max(1,N).
  157.  
  158.      B       (input/output) REAL array, dimension (LDB, N)
  159.              On entry, the second of the pair of matrices.  On exit, B has
  160.              been overwritten by its generalized Schur form T.
  161.  
  162.      LDB     (input) INTEGER
  163.              The leading dimension of B.  LDB >= max(1,N).
  164.  
  165.      SDIM    (output) INTEGER
  166.              If SORT = 'N', SDIM = 0.  If SORT = 'S', SDIM = number of
  167.              eigenvalues (after sorting) for which SELCTG is true.  (Complex
  168.              conjugate pairs for which SELCTG is true for either eigenvalue
  169.              count as 2.)
  170.  
  171.      ALPHAR  (output) REAL array, dimension (N)
  172.              ALPHAI  (output) REAL array, dimension (N) BETA    (output) REAL
  173.              array, dimension (N) On exit, (ALPHAR(j) + ALPHAI(j)*i)/BETA(j),
  174.              j=1,...,N, will be the generalized eigenvalues.  ALPHAR(j) +
  175.              ALPHAI(j)*i and BETA(j),j=1,...,N  are the diagonals of the
  176.              complex Schur form (S,T) that would result if the 2-by-2 diagonal
  177.              blocks of the real Schur form of (A,B) were further reduced to
  178.              triangular form using 2-by-2 complex unitary transformations.  If
  179.              ALPHAI(j) is zero, then the j-th eigenvalue is real; if positive,
  180.              then the j-th and (j+1)-st eigenvalues are a complex conjugate
  181.              pair, with ALPHAI(j+1) negative.
  182.  
  183.              Note: the quotients ALPHAR(j)/BETA(j) and ALPHAI(j)/BETA(j) may
  184.              easily over- or underflow, and BETA(j) may even be zero.  Thus,
  185.              the user should avoid naively computing the ratio.  However,
  186.              ALPHAR and ALPHAI will be always less than and usually comparable
  187.              with norm(A) in magnitude, and BETA always less than and usually
  188.              comparable with norm(B).
  189.  
  190.  
  191.  
  192.  
  193.  
  194.  
  195.                                                                         PPPPaaaaggggeeee 3333
  196.  
  197.  
  198.  
  199.  
  200.  
  201.  
  202. SSSSGGGGGGGGEEEESSSSXXXX((((3333SSSS))))                                                          SSSSGGGGGGGGEEEESSSSXXXX((((3333SSSS))))
  203.  
  204.  
  205.  
  206.      VSL     (output) REAL array, dimension (LDVSL,N)
  207.              If JOBVSL = 'V', VSL will contain the left Schur vectors.  Not
  208.              referenced if JOBVSL = 'N'.
  209.  
  210.      LDVSL   (input) INTEGER
  211.              The leading dimension of the matrix VSL. LDVSL >=1, and if JOBVSL
  212.              = 'V', LDVSL >= N.
  213.  
  214.      VSR     (output) REAL array, dimension (LDVSR,N)
  215.              If JOBVSR = 'V', VSR will contain the right Schur vectors.  Not
  216.              referenced if JOBVSR = 'N'.
  217.  
  218.      LDVSR   (input) INTEGER
  219.              The leading dimension of the matrix VSR. LDVSR >= 1, and if
  220.              JOBVSR = 'V', LDVSR >= N.
  221.  
  222.      RCONDE  (output) REAL array, dimension ( 2 )
  223.              If SENSE = 'E' or 'B', RCONDE(1) and RCONDE(2) contain the
  224.              reciprocal condition numbers for the average of the selected
  225.              eigenvalues.  Not referenced if SENSE = 'N' or 'V'.
  226.  
  227.      RCONDV  (output) REAL array, dimension ( 2 )
  228.              If SENSE = 'V' or 'B', RCONDV(1) and RCONDV(2) contain the
  229.              reciprocal condition numbers for the selected deflating
  230.              subspaces.  Not referenced if SENSE = 'N' or 'E'.
  231.  
  232.      WORK    (workspace/output) REAL array, dimension (LWORK)
  233.              On exit, if INFO = 0, WORK(1) returns the optimal LWORK.
  234.  
  235.      LWORK   (input) INTEGER
  236.              The dimension of the array WORK.  LWORK >= 8*(N+1)+16.  If SENSE
  237.              = 'E', 'V', or 'B', LWORK >= MAX( 8*(N+1)+16, 2*SDIM*(N-SDIM) ).
  238.  
  239.      IWORK   (workspace) INTEGER array, dimension (LIWORK)
  240.              Not referenced if SENSE = 'N'.
  241.  
  242.      LIWORK  (input) INTEGER
  243.              The dimension of the array WORK.  LIWORK >= N+6.
  244.  
  245.      BWORK   (workspace) LOGICAL array, dimension (N)
  246.              Not referenced if SORT = 'N'.
  247.  
  248.      INFO    (output) INTEGER
  249.              = 0:  successful exit
  250.              < 0:  if INFO = -i, the i-th argument had an illegal value.
  251.              = 1,...,N:  The QZ iteration failed.  (A,B) are not in Schur
  252.              form, but ALPHAR(j), ALPHAI(j), and BETA(j) should be correct for
  253.              j=INFO+1,...,N.  > N:  =N+1: other than QZ iteration failed in
  254.              SHGEQZ
  255.              =N+2: after reordering, roundoff changed values of some complex
  256.              eigenvalues so that leading eigenvalues in the Generalized Schur
  257.              form no longer satisfy SELCTG=.TRUE.  This could also be caused
  258.  
  259.  
  260.  
  261.                                                                         PPPPaaaaggggeeee 4444
  262.  
  263.  
  264.  
  265.  
  266.  
  267.  
  268. SSSSGGGGGGGGEEEESSSSXXXX((((3333SSSS))))                                                          SSSSGGGGGGGGEEEESSSSXXXX((((3333SSSS))))
  269.  
  270.  
  271.  
  272.              due to scaling.  =N+3: reordering failed in STGSEN.
  273.  
  274.              Further details ===============
  275.  
  276.              An approximate (asymptotic) bound on the average absolute error
  277.              of the selected eigenvalues is
  278.  
  279.              EPS * norm((A, B)) / RCONDE( 1 ).
  280.  
  281.              An approximate (asymptotic) bound on the maximum angular error in
  282.              the computed deflating subspaces is
  283.  
  284.              EPS * norm((A, B)) / RCONDV( 2 ).
  285.  
  286.              See LAPACK User's Guide, section 4.11 for more information.
  287.  
  288. SSSSEEEEEEEE AAAALLLLSSSSOOOO
  289.      INTRO_LAPACK(3S), INTRO_SCSL(3S)
  290.  
  291.      This man page is available only online.
  292.  
  293.  
  294.  
  295.  
  296.  
  297.  
  298.  
  299.  
  300.  
  301.  
  302.  
  303.  
  304.  
  305.  
  306.  
  307.  
  308.  
  309.  
  310.  
  311.  
  312.  
  313.  
  314.  
  315.  
  316.  
  317.  
  318.  
  319.  
  320.  
  321.  
  322.  
  323.  
  324.  
  325.  
  326.  
  327.                                                                         PPPPaaaaggggeeee 5555
  328.  
  329.  
  330.  
  331.